Help for !CBAdecode (version 1.02)
==================================

 ### See the bottom of this file for recent updates ###

 *  This program is FREEWARE
 *  You may copy/distribute it as much as you like so long as it is not
 *  copied or distributed for profit, or as part of a commercial product.
 *  Use (of application and source) is entirely at your own risk.
 *
 *  This program uses calls and source code from the DeskLib library

This application is designed specifically to make decoding
comp.binaries.acorn postings easier and quicker. It will NOT work with
postings to other usenet or FidoNet groups! (This is because it relies on
some header data that we place when we post files, which cannot be expected
in other groups)

This application can be run in two ways:
(Impressive, huh? How many other RISC OS applications do you know which
can do this? (Not that any others would need to...))


From the desktop
================

Double-click the !CBAdecode icon. A window should appear.

Drag any files that you wish to decode to the window (The order in which you
do this is not important).
You can also drag a directory to the window, and all files inside that
directory (but NOT any files in subdirectories of it) will be scanned.

 =>  And now you can drag files from another application (i.e. your
 =>  newsreader) as well (please see the note at the bottom of this file
 =>  before trying this option!)

As each file is given to the application, it is scanned to find any valid
cba posting parts in it. For every valid posted binary found, an icon that
looks like an archive file icon (Displayed as "Full Info") will appear.

The information on this line indicates the name the post will be saved as,
the approximate size (actually, it is the correct size, rounded UP to the
nearest 37 kilobytes) that it will be when decoded, and the number of parts
that have been found out of the number expected.

When some but not all of the parts have been found, the icon will be grey
and unselectable. Once all the parts have been found, the file will be
automatically selected.

This initial scan is non-multitasking, but usually takes less than a second
on an Arm-2 machine to scan a typical 50kB post message file from a fast
hard drive. From fast file media (ramdisc/hard drive) the operation is
pretty quick, and from slow media the desktop response would be very
sluggish, so you'll have to put up with it singletasking for now...

Once all files have been found (the icon will become a coloured one rather
than greyed out, and will automatically be selected (inverted)), you are
ready to decode the file.

To decode files, select the ones you want, just as in a normal filer window,
and drag them to any filer window. Don't drag them to an application,
because this won't work! (It appears to save into the CSD but don't count on
this property! New versions of the application might try to do something
clever like actually passing the decode file to the app.) As soon as you
complete the drag, uudecoding will begin.

This uudecoding phaze is conducted in the background on the desktop. This
means that most of the time you shouldn't notice its operation too badly,
except where filing operations are slow (this is particularly noticable when 
it is necessary to swap files). The main reason that this multitasks is so
that you can see its progress, and so that you can hit the close-window icon
to quit (and thus abort the operation) at any point.

If a file of the same name as the attempted output file (called, e.g.
"file") exists, names A_file, B_file, C_file ... will be tried. If Z_file
is reached (very unlikely) without finding a unique filename, then
the attempt will be aborted completely.

If you wish to clear the list of files and start fresh, bring up the menu,
and click on "Clear files". The menu also has an info window and a quit
option.

To quit, use the quit on the menu, or simply close the decoder window.


From the command-line (Archimedes or UNIX)
=====================

Run the application with the syntax:
  CBAdecode [options] [list_of_filenames]

e.g.
  CBAdecode csa.95 csa.96 csa.97  (Archimedes)
  CBAdecode csa/95 csa/96 csa/97  (UNIX)

NOTE: Currently, you CANNOT give a directory name or any wildcarded
filenames to the command-line version.

Any complete and valid postings found will be decoded immediately, exactly
as in the WIMP version, but without the fancy WIMP features. Decoded files
will be placed into the CSD (currently selected directory)

CBAdecode has two command-line flags:
  -d          Sets desktop operation mode. This manke CBAdecode try to start
              up as a desktop task. It should only be used in the desktop
              !Run file. DO NOT use it from within a taskwindow!
  -b <size>   Sets the input and output buffer size. Specified in terms of
              kilobytes. The default value is 16 (16 kilobytes), which
              results in an extra 32k (2 buffers) being needed.
              Values <= 4 will result in operating-system buffers being used
              (as these are 4k anyway), but will cause a lot of disc
              seeking, which slows down operation on floppies considerably.
              Values > 64k will not make much of a difference unless all
              posted parts are contained in one large input file.
              Values outside the range 0..128 cause an error.
              Note also, that if memory is not available for the buffers,
              only operating-system buffers will be used (so if you specify
              too large a value, it will drop back to 4k buffers)

(The -b flag is used in the !Run file for desktop operation, and can also be
changed to a default you are happier with)

Operation
=========

The way the program scans for parts means that you do not need to delete
message headers and signatures, concatenate files, or even get them in the
right order - everything is done automatically for you!

In fact, if you do strip headers, the program will FAIL, so just leave the
message files you get from c.b.a alone, and pass them to this program in
their RAW, unprocessed form.

The application will cope with all of the posted messages concatenated into
one (or more) file(s), or a lot of seperate files.

It also handles any mixture of parts from different postings, and repeats of
parts without complaint.

The only thing it won't currently handle is a posting with more than 32
parts in it (which is a 1.6 Megabyte posting...). However, such a large
posting will produce an archive file of approximately 1MB, which is a bit
big for many people to handle anyway, so it is extremely unlikely that
binaries larger than this will be posted on c.b.a. in one archive chunk.


Problem shooting
================

Don't shoot problems. It's antisocial. (Bdooom-Tsh!)

What can you do wrong? Here's a list:
(There are 2 types of error - warnings, which indicate possible problems,
but usually don't affect the outcome of the decode (which are not even
reported under the WIMP), and bad errors, which will cause the application
to abort its attempt to decode that particular posting. (Some very bad
and unlikely errors may even cause the application to quit)

* Not all parts present
  You will not be able to decode a posting until files containing all the
  relevant parts have been supplied. (These incomplete postings are shown on
  the desktop in grey)

* One or more parts duplicated
  The duplicate parts are ignored without comment. (actually, on the
  commandline a warning is given, just ignore it)

* The quoted total number of posted parts changes from one part to another
  Processing of that posting will abort, and the next posting will be
  started. This shouldn't happen unless the messages get corrupted or
  you happen to get 2 different postings under the same name (unlikely!)

* Too many parts in the posting
  The application thinks there are supposed to be (eg) 5 parts in the
  posting, and it has found a part number less than 1 or greater than 5.
  This usually indicates corruption of some of the files.

* Filing errors
  If any problems occur when trying to read or write any files (most likely
  because an input file wasn't found or because the disc is full), the
  application will abort.
  For disc full errors, try decoding only a single post at a time, and
  if necessary, decode to a different disc than the source files are on
  (note that this will require disc swapping unless using 2 drives or a
  RAMdisc)

* UUcode errors
  These are usually fatal (uucode is either right or wrong), and are usually
  caused by parts of the uucode data being corrupted or missing. There isn't
  much that can be done about this - try to get a new copy of the offending
  files.

If anything goes wrong, what can you do to fix it?
* Check that you are giving it the correct set of files, and try again.

* If you still can't get any joy, then you will have to resort to decoding
  the file by hand - strip headers and footers, concatenate all the text
  together in the correct order, and use Spark, SparkFS, or uudecode
  to decode the file.


Decoding files direct from other applications
=============================================

If you drag a file to !CBAdecode from other applications (Edit or a
newsreader most likely), then CBAdecode will save the file as
!CBAdecode.temp.<number>

This temporary file will be used when you subsequently drag archives out to
a filer window.

[NOTE: If you wish to move CBAdecode's temporary workspace, edit the !Run
       file to point CBADecode$TempDir at an appropriate directory]

When you next quit !CBAdecode, ALL files in the !CBAdecode.temp directory
will be wiped. This includes any parts that have not been used.

DON'T delete your original messages until you have a complete, working
archive from CBAdecode - don't expect CCBAdecode to keep the file for you!

*FUTURE* versions of CBAdecode may be upgraded to keep any parts that have
not yet been decoded successfully, so that you can just drag in any new
messages and 'skim off' any completed postings...


Recent updates
==============

This is the 3rd release version of CBAdecode.
Release 1 (version 1.00)

Release 2 (version 1.01 - July '92)
  Added the ability to cope with direct saving to CBAdecode from other
  applications, so you can save messages from your newsreader directly
  into CBAdecode.

Release 3 (version 1.02 - October '92)
  Fixed a couple of bugs which make it fail to work under RISC OS 3.10.
  However, I can't understand how it worked at all! Weird!
  Also added <CBADecode$TempDir> so you can move the applications temporary
  work directory to a more suitable spot...


The author
==========

If you have any bug reports or suggestions to send to the author, or if you
want to offer him an extremely highly paid job and a Porsche (preference,
black 930 or 944), write to:

  *  Jason Williams
  *  R.D.2, Manuel Road,
  *  Silverdale,
  *  North Auckland,
  *  NEW ZEALAND.
  *
  *  jwil1@cs.aukuni.ac.nz (Valid only until Feb. '93)
  *
  *  (Moderator of usenet groups comp.binaries.acorn and comp.sources.acorn)

P.S.
====

Apologies for the humour - I'm in a good mood today ;-)
